home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.arc / gem1.asc next >
Text File  |  1987-10-10  |  16KB  |  347 lines
  1.                       ** Professional GEM **
  2.                            by Tim Oren
  3.  
  4.                       Topic: WINDOWS, part I
  5.                              10/7/85
  6.  
  7.    ANTIC is proud to present the first of Tim Oren's bi-monthly columns
  8. exploring the GEM programming environment.  These columns are aimed
  9. at professional ST developers, but we encourage everyone to join in
  10. and collect the columns for future reference.
  11.  
  12.                           HELLO, WORLD!
  13.  
  14.    For those whom I have not met in person or  electronically, an
  15. introduction is in order.
  16.  
  17.    I am a former member of the GEM programming team at Digital Research,
  18. Inc., where I designed and implemented the GEM Resource Construction
  19. Set and other parts of the GEM Programmer's Toolkit.  I have since
  20. left DRI to become the user interface designer for Activenture, a
  21. startup company which is developing CD-ROM technology for use with
  22. the Atari ST and other systems.
  23.  
  24.    The purpose of Professional GEM is to pass along  some of the
  25. information and tricks I have accumulated about GEM, and explore some
  26. of the user interface techniques which a powerful graphics processor
  27. such as the ST makes possible.
  28.  
  29.                            GROUND RULES
  30.  
  31.    I am going to assume that you have both a working  knowledge of the C
  32. programming language and a copy of the ST Programmer's Toolkit with
  33. documentation (available from Atari).  If you lack either, don't
  34. panic.  You can read the columns to get the flavor of programming the
  35. ST, and come back for a more serious visit later on.
  36.  
  37.    For now, I will be using code samples that will run with the
  38. Atari-supplied C compiler, also known as DR C-68K, or Alcyon C.  I
  39. will be using the portability macros supplied with the Toolkit, so
  40. that the code will also be transferable to other GEM systems.
  41.  
  42.    Both of these items are subject to change, depending on  reader
  43. feedback and the availability of better products.
  44.  
  45.    If you do not have a copy of the source to the DOODLE.C GEM example
  46. program, you should  consider downloading a copy from SIG*ATARI.
  47. Although it is poorly documented, it shows real-life examples of many
  48. of the techniques I will  discuss.
  49.  
  50.    Getting started with a windowed graphics system seems to be like
  51. getting into an ice-cold swimming pool: it's best done all at once.
  52.  
  53.    Anyone who has looked at "Inside Macintosh" has probably noticed that
  54. you have to have read most of it to understand any of it.  GEM isn't
  55. really much  different.  You have all the reference guides in your
  56. hand, but nothing to show how it all works together.
  57.  
  58.    I am hoping to help this situation by leading a series of short tours
  59. through the GEM jungle.  Each time we'll go out with a particular
  60. goal in mind and follow the path that leads there.  We'll look at the
  61. pitfalls and strange bugs that lurk for the unwary, and show off a
  62. few tricks to  amaze the natives.  The first trip leaves immediately;
  63. our mission is to get a window onto the ST screen, with all of its
  64. parts properly initialized.
  65.  
  66.                           WE DO WINDOWS
  67.  
  68.    One of the most important services which a graphics interface system
  69. provides for the user and programmer is window management.
  70.  
  71.    Windows allow the user to perform more than one activity on the same
  72. screen, to freely reallocate areas of the screen for each task, and
  73. even to pile the information up like pages of paper to make more
  74. room.  The price for this increased freedom is (as usual) paid by
  75. you, the programmer, who must master a more complex method of
  76. interacting with the "outside world".
  77.  
  78.    The windowing routines provided by ST GEM are the most comprehensive
  79. yet available in a low-cost microcomputer.  This article is a guide
  80. to using these services in an effective manner.
  81.  
  82.                          IN THE BEGINNING
  83.  
  84.    In GEM, creating a window and displaying it are two different
  85. functions.  The creation function is called wind_create, and its
  86. calling sequence is:
  87.  
  88.    handle = wind_create(parts, xfull, yfull, wfull, hfull);
  89.  
  90.    This function asks GEM to reserve space in its memory for a new
  91. window  description, and to return a code or "handle" which you can
  92. use to refer to the window in the future.  Valid window handles are
  93. positive integers; they are not memory pointers.
  94.  
  95.    GEM can run out of window handles.  If it does so, the value returned
  96. is negative.  Your code should always check for this  situation and
  97. ask the program's user to close some windows and retry if  possible.
  98. Handle zero is special.  It refers to the "desktop", which is
  99. predefined as light green (or gray) on the ST.  Window zero is always
  100. present and may be used, but never deleted, by the programmer.
  101.  
  102.    The xfull, yfull, wfull, and hfull parameters are integers which
  103. determine the maximum size of the window.  Xfull and yfull define the
  104. upper left corner of the window, and wfull and hfull specify its
  105. width and height. (Note that all of the window coordinates which we
  106. use are in pixel units.)
  107.  
  108.    GEM saves these values so that the program can get them later when
  109. processing  FULL requests.  Usually the best maximum size for a
  110. window is the entire desktop area, excepting the menu bar.  You can
  111. find this by asking wind_get  for the working area of the desktop
  112. (handle zero, remember):
  113.  
  114.    wind_get(0, WF_WXYWH, &xfull, &yfull, &wfull, &hfull);
  115.  
  116.    Note that WF_WXYWH, and all of the other mnemonics used in this
  117. article, are defined in the GEMDEFS.H file in the ST Toolkit.
  118.  
  119.    The parts parameter of wind_create defines what features will be
  120. included in the window when it is drawn.  It is a word of single bit
  121. flags which indicate the presence/absence of each feature.  To
  122. request multiple features, the flags are "or-ed" together. The flags'
  123. mnemonics and meanings are:
  124.  
  125.    NAME- A one character high title bar at the top of the window.
  126.  
  127.    INFO- A second character line below the NAME.
  128.  
  129.    MOVER- This lets the user move the window around by "dragging"  in
  130. the NAME area.  NAME also needs to be defined.
  131.  
  132.    CLOSER  - A square box at the upper left.  Clicking this control
  133. point asks that the window be removed from the screen.
  134.  
  135.    FULLER  - A diamond at upper right.  Clicking this control point
  136. requests that the window grow to its maximum size, or  shrink back
  137. down if it is already big.
  138.  
  139.    SIZER   - An arrow at bottom right.  Dragging the SIZER lets  the
  140. user choose a new size for the window.
  141.  
  142.    VSLIDE  - defines a right-hand scroll box and bar for the window.
  143. By dragging the scroll bar, the user requests that the  window's
  144. "viewport" into the information be moved.   Clicking on the gray box
  145. above the bar requests that  the window be moved up one "page".
  146. Clicking below the  bar requests a down page movement.  You have to
  147. define  what constitutes a page or line in the context of your
  148. application.
  149.  
  150.    UPARROW - An arrow above the right scroll bar.  Clicking here
  151. requests that the window be moved up one "line".  Sliders and arrows
  152. almost always appear together.
  153.  
  154.    DNARROW - An arrow below the right scroll bar.  Requests that  window
  155. be moved down a line.
  156.  
  157.    HSLIDE  - These features are the horizontal equivalent of the
  158. RTARROW   above.  They appear at the bottom of the window.  Arrows
  159. LFARROW  usually indicate "character" sized movement left and right.
  160. "Page" sized movement has to be defined by each application.
  161.  
  162.    It is important to understand the correspondence between window
  163. features and event messages which are sent to the application by the
  164. GEM window manager.  If a feature is not included in a window's
  165. creation,  the user cannot perform the corresponding action, and your
  166. application will  never receive the matching message type.  For
  167. example, a window without a  MOVER may not be dragged by the user,
  168. and your app will never get a WM_MOVED  message for that window.
  169.  
  170.    Another important principle is that the application itself is
  171. responsible for implementing the user's window action request when a
  172. message is received.  This gives the application a chance to accept,
  173. modify, or reject the user's request.
  174.  
  175.    As an example, if a WM_MOVED message is received, it indicates that
  176. the user has dragged the window.  You might want to byte or word
  177. align the requested position before proceeding to